<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2008 XBRL International. All Rights Reserved. -->
<?xml-stylesheet type="text/xsl" href="../stylesheets/functionDefinition.xsl"?>
<function
  xmlns="http://xbrl.org/2008/function" 
  xmlns:reg="http://xbrl.org/2008/registry" 
  xmlns:xhtml="http://www.w3.org/1999/xhtml" 
  xmlns:xfi="http://www.xbrl.org/2008/function/instance" 
  xmlns:xfie="http://www.xbrl.org/2008/function/instance/error" 
  xmlns:xbrli="http://www.xbrl.org/2003/instance" 
  xmlns:xlink="http://www.w3.org/1999/xlink" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="
  http://xbrl.org/2008/registry ../schemas/registry.xsd
  http://xbrl.org/2008/function ../schemas/function.xsd
  ">

  <lastUpdated moment="2011-03-16T11:00:00" />

  <owners>
    <reg:owner id="herm">
       <reg:name>Herm Fischer</reg:name>
      <reg:affiliation>UBMatrix / Mark V Systems</reg:affiliation>
       <reg:email>fischer@markv.com</reg:email>
       <reg:assumedOwnership moment="2008-09-01T00:00:00" />
    </reg:owner>
    <reg:owner id="geoff">
       <reg:name>Geoff Shuetrim</reg:name>
      <reg:affiliation>Galexy</reg:affiliation>
       <reg:email>geoff@galexy.net</reg:email>
       <reg:assumedOwnership moment="2008-11-11T00:00:00" />
       <reg:relinquishedOwnership moment="2008-11-12T00:00:00"/>
    </reg:owner>
    <reg:owner id="davod">
       <reg:name>David North</reg:name>
      <reg:affiliation>CoreFiling</reg:affiliation>
       <reg:email>dtn@corefiling.com</reg:email>
       <reg:assumedOwnership moment="2011-09-19T09:22:09" />
    </reg:owner>
  </owners>

  <summary>
    Returns a sequence containing a select set of dimension member
    QNames for the specified explicit dimension considering
    only those members that have the specified relationship axis
    to the specified origin member 
    in the network of effective relationships with the specified link role 
    for the specified arc role.  
    The set of dimension member QNames is in an arbitrary order (not
    necessarily that of effective tree relationships order).
  </summary>

  <documentation>
    <xhtml:p>
    Note that the relationships can be expressed
    by an arc element that conforms to the requirements set out in the XBRL 2.1 
    specification.  Importantly, the relationships do not have to be expressed by
    XBRL 2.1 definition arc elements and they do not have to have arcroles defined
    in the XBRL Dimensions specification. 
    </xhtml:p>
    <xhtml:p>
    Note that if the QName given for the member argument is not a member of
    the relevant explicit dimension, the function returns the empty sequence.
    </xhtml:p>
  </documentation>

  <signature name="xfi:filter-member-network-selection">

    <input name="dimension" type="xs:QName">
      <xhtml:p>
        The QName of the dimension. This input is provided so that the function can check that the members selected from the network are members of the dimension, and only return those that are.
      </xhtml:p>
    </input>

    <input name="member" type="xs:QName">
      <xhtml:p>
        The QName of the dimension member that the selection criteria specified by the axis
        parameter are going to be applied relative to.
      </xhtml:p>
    </input>

    <input name="linkrole" type="xs:string">
      <xhtml:p>
        The linkrole value that specifies the network of effective
        relationships to determine the selected members on the specified
        axis from the member used as the origin.
      </xhtml:p>
    </input>

    <input name="arcrole" type="xs:string">
      <xhtml:p>
        The arcrole value that specifies the network of effective
        relationships as above.
      </xhtml:p>
    </input>

    <input name="axis" type="xs:string">
      <xhtml:p>
        The axis value MUST be one of:
      </xhtml:p>
      <xhtml:ul>
        <xhtml:li>descendant-or-self</xhtml:li>
        <xhtml:li>child-or-self</xhtml:li>
        <xhtml:li>descendant</xhtml:li>
        <xhtml:li>child</xhtml:li>
      </xhtml:ul>

      <xhtml:p>
        If the axis value is 'child' then the result includes those domain members in the explicit dimension domain that are targets of effective arcrole relationships from the member identified by QName in the linkrole network. 
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'child-or-self' then the result includes the domain member identified by the member QName and those domain members in the explicit dimension domain that are targets of effective arcrole relationships from the domain member identified by QName value. 
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'descendant' then the filter-member set includes those domain members in the explicit dimension domain that are descendants of the member QName, in the linkrole network of arcrole effective relationships.
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'descendant-or-self' then the filter-member set includes includes the domain member identified by the member QName and those domain members in the explicit dimension domain that are descendants of the member QName, in the linkrole network of arcrole effective relationships.
      </xhtml:p>
    </input>

    <output type="xs:QName*">
      <xhtml:p>
        Returns a sequence which is the set of reportable dimension member QNames for the specified
        explicit dimension per the inputs described above. (Note: the definition of a set
        requires that it have distinct members.)
      </xhtml:p>
    </output>
  </signature>

  <error code="xfie:invalidDimensionQName">
    <xhtml:p>
      This error MUST be thrown if the dimension is not in the reference
      discoverable taxonomy set.
    </xhtml:p>
  </error>

  <!-- removed error codes 2011-03-10
  <error code="xfie:unrecognisedExplicitDimensionValueQName">
    <xhtml:p>
      This error MUST be thrown if the member is not in one of the networks
      of relationships between dimension members that are identified by the 
      linkrole and arcrole parameters of the function.
    </xhtml:p>
  </error>

  <error code="xfie:ambiguousFilterMemberNetwork" >
    <xhtml:p>
        This error MUST be thrown if the filter-member network is not uniquely determined from the DTS by the filter-member linkrole and filter-member arcrole. 
    </xhtml:p>
    <xhtml:p>
This error could occur for a DTS in which the same combination of linkrole and arcrole values were being used with two different extended link elements or two different arc elements. 
    </xhtml:p>
  </error>
  
  -->

  <conformanceTest xlink:type="simple" xlink:href="90213 xfi.filter-member-network-selection testcase.xml"/>

  <revisions>
    <reg:revision on="2008-09-01T00:00:00" by="herm">
      <xhtml:p>
        Created the function definition.
      </xhtml:p>
    </reg:revision>
    <reg:revision on="2008-09-02T00:00:00" by="herm">
      <xhtml:p>
        Added error code xbrldfe:ambiguousFilterMemberNetwork.
      </xhtml:p>
    </reg:revision>
    <reg:revision on="2008-11-11T00:00:00" by="geoff">
      <xhtml:p>
        Updated the wording for the xfie:unrecognisedExplicitDimensionValueQName error code.
      </xhtml:p>
    </reg:revision>
    <reg:revision on="2009-03-19T00:00:00" by="geoff">
      <xhtml:p>
        Added documentation clarifying the generality of the function.
      </xhtml:p>
    </reg:revision>

    <reg:revision on="2010-09-09T00:00:00" by="herm">
      <xhtml:p>
        Changed input role URIs to strings for cast-less coding and to be similar to fn:QName's $paramURI, an xs:string.
      </xhtml:p>
    </reg:revision>

    <reg:revision on="2011-03-10T23:00:00" by="herm">
      <xhtml:p>
        Removed error unrecognisedExplicitDimensionValueQName because this prevents use of the function when
        the formula author can not know in advance whether an extended link role network contains a dimension, such
        as when iterating over extended link roles of an SEC or IFRS filing to find dimensional networks.  Removed
        ambiguousFilterMemberNetwork error because its original purpose is no longer relevant or applicable.
      </xhtml:p>
    </reg:revision>

    <reg:revision on="2011-03-16T11:00:00" by="herm">
      <xhtml:p>
        Clarified that the result, as originally described, is a set, which must by definition have
        distinct members.
      </xhtml:p>
    </reg:revision>

    <reg:revision on="2011-09-19T09:22:35" by="david">
      <xhtml:p>
        Clarified that when the member argument is not a member of the relevant dimension, the empty
        set should be returned.
      </xhtml:p>
    </reg:revision>
  </revisions>

</function>
